Add TCPRoute and UDPRoute Support for L4 Load Balancing #3688

Skcey · 2025-08-05T09:21:02Z

Proposed changes

Problem:
NGF currently lacks support for TCPRoute and UDPRoute resources, which are essential for managing Layer 4 (TCP/UDP) traffic via the Gateway API.

Solution:
This PR adds basic support for TCPRoute and UDPRoute to NGF, enabling Layer 4 load balancing. Key implementations include:

Added controllers to watch and process TCPRoute/UDPRoute resources, following the pattern used for HTTPRoute/TLSRoute.
Implemented route construction logic in the state graph to resolve listeners, backend services, and reference grants for L4 routes.
Extended the NGINX stream configuration generator to create upstream groups and server blocks for TCP/UDP traffic, mapping routes to their backend services.

Testing:
Packaged into an image and tested in my environment.

Closes #3687

Checklist

Before creating a PR, run through this checklist and mark each as complete.

[ ✔️] I have read the CONTRIBUTING doc
[✔️ ] I have added tests that prove my fix is effective or that my feature works
I have checked that all unit tests pass after adding my changes
I have updated necessary documentation
[ ✔️] I have rebased my branch onto main
[ ✔️] I will ensure my PR is targeting the main branch and pulling from my branch from my own fork

Release notes

If this PR introduces a change that affects users and needs to be mentioned in the release notes,
please add a brief note that summarizes the change.

nginx-bot · 2025-08-05T09:21:06Z

Hi @Skcey! Welcome to the project! 🎉

Thanks for opening this pull request!
Be sure to check out our Contributing Guidelines while you wait for someone on the team to review this.

github-actions · 2025-08-05T09:21:16Z

✅ All required contributors have signed the F5 CLA for this PR. Thank you!
_{Posted by the CLA Assistant Lite bot.}

Skcey · 2025-08-05T10:09:52Z

I have hereby read the F5 CLA and agree to its terms

Skcey · 2025-08-05T10:10:19Z

recheck

| datasource | package | from | to | | ----------- | --------------------- | ------- | ------- | | github-tags | goreleaser/goreleaser | v2.11.1 | v2.11.2 | Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>

| datasource | package | from | to | | ----------- | -------------------------- | ------- | ------- | | github-tags | google-github-actions/auth | v2.1.11 | v2.1.12 | Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>

| datasource | package | from | to | | ----------- | ---------------------- | ------ | ------ | | github-tags | golangci/golangci-lint | v2.3.0 | v2.3.1 | Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>

| datasource | package | from | to | | ----------- | ---------------------- | ------ | ------ | | github-tags | docker/metadata-action | v5.7.0 | v5.8.0 | Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>

) | datasource | package | from | to | | ---------- | ----------------------------------- | ------- | ------- | | go | github.com/prometheus/client_golang | v1.22.0 | v1.23.0 | Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>

Adjust logging when resolving endpoints so that it no longer sends an error message but is instead a debug log message. Also, add a debug log message upon successful resolving of endpoints.

…x#3623)

Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>

| datasource | package | from | to | | ----------- | ------------------- | ------ | ------ | | github-tags | docker/login-action | v3.4.0 | v3.5.0 | Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>

| datasource | package | from | to | | ----------- | --------------------------- | ------- | ------- | | github-tags | reviewdog/action-actionlint | v1.65.2 | v1.66.0 | Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>

Add connection to NGINX One Console by configuring Agent to sent telemetry data to NGINX One Console endpoint. Problem: Users of NGF and NGINX One Console would like to see fleet management telemetry in their console. Solution: Update NGINX Agent configuration to send telemetry data to NGINX One Console when a user specifies their data plane key secret. Testing: Added unit tests and manually verified NGF metrics are sent to the NGINX One Console when using a staging endpoint.

| datasource | package | from | to | | ----------- | ------------------- | ------ | ------ | | github-tags | anchore/scan-action | v6.5.0 | v6.5.1 | Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>

| datasource | package | from | to | | ----------- | ------------------------- | ------ | ------ | | github-tags | actions/download-artifact | v4.3.0 | v5.0.0 | Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>

Problem: In some environments, Pods could share an IP address (for example when a Job completes and a new Pod grabs that IP). This would cause problems when the nginx data plane Pod would attempt to connect to the control plane. The control plane would try to validate the token provided by the nginx agent, by using the IP address in the request to lookup the associated Pod. If multiple Pods existed with that IP address, the control plane would error out. Solution: Fix the control plane logic to use more criteria when getting the proper Pod to verify the provided token.

…3695)

| datasource | package | from | to | | ---------- | ----------------------- | ------- | ------- | | helm | opentelemetry-collector | 0.130.0 | 0.130.1 | Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>

| datasource | package | from | to | | ----------- | -------------------- | ------- | ------- | | github-tags | github/codeql-action | v3.29.5 | v3.29.8 | Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>

| datasource | package | from | to | | ----------- | ------------- | ------ | ------ | | github-tags | actions/cache | v4.2.3 | v4.2.4 | Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>

* Update module google.golang.org/protobuf to v1.36.7 | datasource | package | from | to | | ---------- | -------------------------- | ------- | ------- | | go | google.golang.org/protobuf | v1.36.6 | v1.36.7 | Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * Update tests directory --------- Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> Co-authored-by: Saylor Berman <[email protected]>

| datasource | package | from | to | | ----------- | --------------------- | ------- | ------- | | github-tags | goreleaser/goreleaser | v2.12.3 | v2.12.4 | Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>

| datasource | package | from | to | | ----------- | --------------------- | ------ | ------ | | github-tags | ossf/scorecard-action | v2.4.2 | v2.4.3 | Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>

Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>

Update main docs for Release 2.1.3.

Update with NFR test results for NGF version edge ["oss","plus"] Co-authored-by: nginx-bot <[email protected]> Co-authored-by: bjee19 <[email protected]>

Update Dockerfile alpine packages libcrpyto3 and libssl3 to fix cves.

Update main docs for Release 2.1.4.

Skcey · 2025-10-02T07:09:07Z

Hi @Skcey. Thank you again for your contribution to NGF and for initiating this feature! We think this is an excellent addition and really appreciate the hard work you've put into it. We noticed that you haven't had a chance to address the comments yet, which is completely understandable as life can get busy. Since L4 Load Balancing is a sought after addition, we'd be happy to help finish up the remaining steps to get it merged. Please let us know if you'd like us to proceed.

Alternatively, if you'd like to continue working on this, that's ok too, so feel free to reach out. There’s no rush, and we’re happy to assist you with any questions or clarifications.

I'm truly sorry for letting this matter linger for so long due to my personal reasons. Currently, I've sorted out all my personal affairs and was just planning to wrap up this feature soon. However, I'm aware of my limited capabilities, and the progress might be a bit slow. My current plan is to spend one week finishing it，starting from now. If there's no real urgency on your end, could you please give me one more week to finish the remaining work on my own? If time is pressing, I'd also be very grateful if you could step in directly to help complete the rest.

| datasource | package | from | to | | ---------- | ----------------- | ---- | ---- | | docker | docker/dockerfile | 1.18 | 1.19 | Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>

mkingst · 2025-10-02T08:45:15Z

@Skcey No need to apologise at all! We were just checking in to see if you needed any additional support. The feature is fantastic and something we had even planned to do ourselves, so we really appreciate you taking it on. Looking forward to seeing your updates, and feel free to reach out if you need any help!

…nx#3999) | datasource | package | from | to | | ---------- | ---------------------------------------- | ------ | ------ | | go | github.com/nginx/nginx-gateway-fabric/v2 | v2.1.1 | v2.1.4 | Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>

| datasource | package | from | to | | ----------- | --------------------- | ------- | ------- | | github-tags | goreleaser/goreleaser | v2.12.4 | v2.12.5 | Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>

Problem: As a cluster operator managing traffic for an OpenShift cluster I want easily deploy NGF as my Gateway API implementation from the Operator Hub So that it is easier for me to try out and use NGF for my OpenShift environment. Solution: Add UBI based images and an Operator so we can begin the RedHat Operator Certification process and get NGF into the RedHat Certified OperatorHub

…c406 (nginx#4013) Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>

| datasource | package | from | to | | ----------- | ----------- | ------ | ------ | | github-tags | nginx/agent | v3.3.1 | v3.3.2 | Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>

| datasource | package | from | to | | ----------- | ------------- | ------- | ------- | | github-tags | actions/stale | v10.0.0 | v10.1.0 | Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>

| datasource | package | from | to | | ----------- | -------------------- | ------- | ------- | | github-tags | github/codeql-action | v3.30.5 | v3.30.6 | Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>

| datasource | package | from | to | | ---------- | ----------------- | ---- | ---- | | docker | docker/dockerfile | 1.18 | 1.19 | Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>

| datasource | package | from | to | | ---------- | ------------------------- | ------- | ------- | | go | github.com/onsi/ginkgo/v2 | v2.25.3 | v2.26.0 | Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>

updates: - [github.com/scop/pre-commit-shfmt: v3.11.0-1 → v3.12.0-2](scop/pre-commit-shfmt@v3.11.0-1...v3.12.0-2) Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Update operator controller name to include operator and add required annotation for OpenShift

| datasource | package | from | to | | ---------- | ------------------------------ | ------- | ------- | | go | sigs.k8s.io/controller-runtime | v0.22.1 | v0.22.2 | Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>

Add TCPRoute and UDPRoute Support for L4 Load Balancing

7a6c74d

Skcey requested a review from a team as a code owner August 5, 2025 09:21

github-project-automation bot added this to NGINX Gateway Fabric Aug 5, 2025

github-project-automation bot moved this to 🆕 New in NGINX Gateway Fabric Aug 5, 2025

nginx-bot bot added the community label Aug 5, 2025

github-actions bot added the enhancement New feature or request label Aug 5, 2025

Merge branch 'main' into feature/tcproute-udproute

728139f

renovate bot and others added 19 commits August 5, 2025 08:41

Adjust logging when resolving endpoints (nginx#3690)

0651c28

Adjust logging when resolving endpoints so that it no longer sends an error message but is instead a debug log message. Also, add a debug log message upon successful resolving of endpoints.

Add CEL validation test for targetRef in ClientSettingsPolicy (ngin…

966d874

…x#3623)

Lock file maintenance (nginx#3681)

8defcb7

Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>

Add CEL validation test for timeout in ClientSettingsPolicy (nginx#…

206b84e

…3695)

renovate bot and others added 7 commits October 1, 2025 08:28

Lock file maintenance (nginx#3986)

9010072

Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>

Update main docs for release 2.1.3 (nginx#3990)

ff17b7f

Update main docs for Release 2.1.3.

NFR Test Results for NGF version edge (nginx#3991)

d32ef5a

Update with NFR test results for NGF version edge ["oss","plus"] Co-authored-by: nginx-bot <[email protected]> Co-authored-by: bjee19 <[email protected]>

Fix cves for libcrpyto3 and libssl3 (nginx#3993)

8f7b093

Update Dockerfile alpine packages libcrpyto3 and libssl3 to fix cves.

Update main docs for release 2.1.4 (nginx#3997)

9e6c265

Update main docs for Release 2.1.4.

github-actions bot removed the stale Pull requests/issues with no activity label Oct 2, 2025

renovate bot and others added 15 commits October 2, 2025 09:55

Update ghcr.io/nginx/dependencies/nginx-ubi:ubi9 Docker digest to 073…

8f5cd73

…c406 (nginx#4013) Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>

Add plus secrets for image building in tests (nginx#4020)

6e22e50

Add labels and license file to NGF UBI Dockerfile (nginx#4021)

7af7901

[pre-commit.ci] pre-commit autoupdate (nginx#4023)

cb31ea4

updates: - [github.com/scop/pre-commit-shfmt: v3.11.0-1 → v3.12.0-2](scop/pre-commit-shfmt@v3.11.0-1...v3.12.0-2) Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Update operator controller name & add annotation (nginx#4026)

f133cfb

Update operator controller name to include operator and add required annotation for OpenShift

Merge branch 'feature/tcproute-udproute'

b9969f9

Skcey requested a review from a team as a code owner October 7, 2025 18:39

github-actions bot added documentation Improvements or additions to documentation dependencies Pull requests that update a dependency file helm-chart Relates to helm chart labels Oct 7, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add TCPRoute and UDPRoute Support for L4 Load Balancing #3688

Add TCPRoute and UDPRoute Support for L4 Load Balancing #3688

Skcey commented Aug 5, 2025

Uh oh!

nginx-bot bot commented Aug 5, 2025

Uh oh!

github-actions bot commented Aug 5, 2025 •

edited

Loading

Uh oh!

Skcey commented Aug 5, 2025

Uh oh!

Skcey commented Aug 5, 2025

Uh oh!

Skcey commented Oct 2, 2025

Uh oh!

mkingst commented Oct 2, 2025

Uh oh!

Uh oh!

Add TCPRoute and UDPRoute Support for L4 Load Balancing #3688

Are you sure you want to change the base?

Add TCPRoute and UDPRoute Support for L4 Load Balancing #3688

Conversation

Skcey commented Aug 5, 2025

Proposed changes

Checklist

Release notes

Uh oh!

nginx-bot bot commented Aug 5, 2025

Uh oh!

github-actions bot commented Aug 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Skcey commented Aug 5, 2025

Uh oh!

Skcey commented Aug 5, 2025

Uh oh!

Skcey commented Oct 2, 2025

Uh oh!

mkingst commented Oct 2, 2025

Uh oh!

Uh oh!

github-actions bot commented Aug 5, 2025 •

edited

Loading